home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / misc / dmalloc.man < prev    next >
Encoding:
Text File  |  1991-11-15  |  8.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DMALLOC               C Library Procedures                DMALLOC
  5.  
  6.  
  7.  
  8. NNAAMMEE
  9.      dmalloc - debugging malloc library
  10.  
  11. SSYYNNOOPPSSIISS
  12.      cccc [[ ffllaaggss ]] ffiilleess --llddmmaalllloocc [[lliibbrraarriieess]]
  13.  
  14.      ##iinncclluuddee ""//sspprriittee//ssrrcc//lliibb//ddmmaalllloocc//mmaalllloocc..hh""
  15.  
  16.      cchhaarr ** ccaalllloocc((nneelleemm,,eellssiizzee));;
  17.      vvooiidd   ffrreeee((ppttrr));;
  18.      cchhaarr ** mmaalllloocc((ssiizzee));;
  19.      iinntt    mmaalllloocc__cchhaaiinn__cchheecckk((ffllaagg));;
  20.      vvooiidd   mmaalllloocc__dduummpp((ffdd));;
  21.      iinntt    mmaalllloopptt((ccmmdd,,vvaalluuee))
  22.      cchhaarr ** rreeaalllloocc((ppttrr,,ssiizzee));;
  23.  
  24.      iinntt         ccmmdd,,ffdd,,ffllaagg;;
  25.      uunnssiiggnneedd    eellssiizzee,,nneelleemm,,ssiizzee;;
  26.      cchhaarr      ** ppttrr;;
  27.      uunniioonn vvaall   vvaalluuee;;
  28.  
  29.  
  30. DDEESSCCRRIIPPTTIIOONN
  31.      This malloc library is a replacement for the standard
  32.      library to be used during software development/debugging.
  33.      The library can be used without source code modification,
  34.      just by linking it in.  This library is useful for finding
  35.      trashed memory, but isn't useful for finding memory leaks.
  36.      See the standard malloc(3) pages for more information on the
  37.      use of the following functions:
  38.           calloc(), free(), malloc(), realloc()
  39.  
  40.      This library differs from the standard malloc library in the
  41.      following ways:
  42.  
  43.      1. Each malloc segment contains a magic number so that free
  44.      can verify that the pointer passed points to a valid malloc
  45.      segment.
  46.  
  47.      2. Each malloc segment is filled with a non-zero pattern so
  48.      that code that depends upon malloc segments being null will
  49.      fail.
  50.  
  51.      3. The size of each segment will be at least 1 byte larger
  52.      than requested and the extra bytes will be filled with a
  53.      non-zero pattern.  When free is called, it will verify that
  54.      you did not go beyond the number of bytes you asked for.
  55.  
  56.      4. When a segment is freed, it will be filled with a dif-
  57.      ferent non-zero pattern to ensure that the program doesn't
  58.      depend upon the use of already freed data.
  59.  
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DMALLOC               C Library Procedures                DMALLOC
  71.  
  72.  
  73.  
  74.      5. Whenever any of the string or memory functions (str*, b*,
  75.      mem*) are called with a pointer that is within the malloc
  76.      arena,  the operation is checked to verify that it does not
  77.      overrun the malloced segment.  A failure of this check is
  78.      considered a "warning level error" (described later) and is
  79.      handled accordingly.
  80.  
  81.      7. Run time checking can include verification of the malloc
  82.      chain at each and every call to one of the malloc functions
  83.      or manually by calling the malloc_chain_check function.
  84.  
  85.      6. When a problem is found, the action taken is specified at
  86.      runtime by environment variables or at compile time by the
  87.      use of the mallopt() function.
  88.  
  89.      There are two arbitrary levels of errors, warning and fatal,
  90.      that this library will detect.  They are broken down as fol-
  91.      lows:
  92.  
  93.        Warning messages include:
  94.  
  95.          Calling free with a bad pointer
  96.          Calling a bstring/string/memory (3) function which will go beyond
  97.             the end of a malloc block. Note that the library function is
  98.             not modified to refuse the operation.
  99.  
  100.        Fatal errors are:
  101.          Detectable corruption to the malloc chain.
  102.  
  103.      The error handling for each level (warning or fatal) are specified using
  104.      environment variables or mallopt().  The coding for the error handling is
  105.      as follows:
  106.  
  107.          0 - continue operations
  108.          1 - drop core and exit
  109.          2 - just exit
  110.          3 - drop core, but continue executing.  Core files will
  111.           be placed into core.[PID].[counter] i.e: core.00123.001
  112.        128 - dump malloc chain and continue
  113.        129 - dump malloc chain, dump core, and exit
  114.        130 - dump malloc chain, exit
  115.        131 - dump malloc chain, dump core, continue processing
  116.  
  117.      In addition error messages can be placed into an error file.
  118.  
  119.      mmaalllloocc__oopptt() is used to set the malloc debugging options. The
  120.      following options can be set:
  121.  
  122.           MALLOC_WARN - set the error handling for warning level errors.  vvaall is
  123.           an integer that can contain any one of the following values:
  124.  
  125.                M_HANDLE_IGNORE - ignore error
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DMALLOC               C Library Procedures                DMALLOC
  137.  
  138.  
  139.  
  140.                M_HANDLE_ABORT - drop core and exit
  141.                M_HANDLE_EXIT - just exit (no core drop)
  142.                M_HANDLE_CORE - drop core, but keep on going
  143.  
  144.           In addition, M_HANDLE_DUMP may be or'd in to cause a dump of the current
  145.           malloc chain.
  146.  
  147.           MALLOC_FATAL - set the error handling for fatal level errors.  vvaall is
  148.           equivalent to vvaall for MALLOC_WARN.
  149.  
  150.           MALLOC_ERRFILE - set the destination for malloc error messages.  vvaall is
  151.           a pointer to a character string containing the name of the file to be used
  152.           for error messages.
  153.  
  154.           MALLOC_CKCHAIN - set the malloc chain checking flag.  If vvaall is
  155.           non-zero, chain checking at every call to malloc is turned on.
  156.  
  157.           For example, to set up the session to generate a core file for
  158.           every malloc warning, to drop core and exit on a malloc fatal, and
  159.           to log all messages to the file "malloc_log" do the following:
  160.  
  161.                #include <malloc.h>
  162.                malloc_opt(MALLOC_WARN,131);
  163.                malloc_opt(MALLOC_FATAL,1);
  164.                malloc_opt(MALLOC_ERRFILE,"malloc_log");
  165.  
  166.      mmaalllloocc__oopptt() can be used to set/alter the debugging options
  167.      at any time.
  168.  
  169.      mmaalllloocc__dduummpp() will dump a table of the malloc arena showing
  170.      all allocated/freed segments and the first few bytes of data
  171.      in each segment.  ffdd is the file descriptor to write the
  172.      data to.
  173.  
  174.      mmaalllloocc__cchhaaiinn__cchheecckk() will check the status of the malloc
  175.      arena.  If ffllaagg is non-zero, an error found in the chain
  176.      will cause a fatal error.  mmaalllloocc__cchhaaiinn__cchheecckk() returns zero
  177.      when there are no problems found in the malloc chain, non-
  178.      zero otherwise.
  179.  
  180. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
  181.      Environment variables can be used to control error handling,
  182.      error logging and malloc chain checking at run time.  The
  183.      following environment variables are used:
  184.  
  185.      MALLOC_WARN - specifies the error handling for warning
  186.      errors
  187.      MALLOC_FATAL - specifies the error handling for fatal errors
  188.      MALLOC_ERRFILE - specifies the error log file for error mes-
  189.      sages.
  190.      MALLOC_CKCHAIN - if 1, turns on malloc chain checking at
  191.      every call to any of the malloc functions.
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DMALLOC               C Library Procedures                DMALLOC
  203.  
  204.  
  205.  
  206.      For example, to set up the session to generate a core file
  207.      for every malloc warning, to drop core and exit on a malloc
  208.      fatal, and to log all messages to the file "malloc_log" do
  209.      the following:
  210.  
  211.           MALLOC_WARN=131
  212.           MALLOC_FATAL=1
  213.           MALLOC_ERRFILE=malloc_log
  214.  
  215.           export MALLOC_WARN MALLOC_FATAL MALLOC_ERRFILE
  216.  
  217. WWAARRNNIINNGGSS
  218.      This malloc library and it's associated string and memory
  219.      functions are much less efficient than the standard func-
  220.      tions due in part to the extra error checking.  You do not
  221.      want to use this library when generating a production (i.e.
  222.      releasable) version of your software.  It should only be
  223.      used during development and testing.
  224.  
  225. SSEEEE AALLSSOO
  226.      stat(2)
  227.  
  228. AAUUTTHHOORR
  229.      Conor P. Cahill Virtual Technologies Incorporated
  230.  
  231.      uunet!virtech!cpcahil
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Sprite v1.0                                                     4
  262.  
  263.  
  264.  
  265.